home *** CD-ROM | disk | FTP | other *** search
/ Game Programming in C++ - Start to Finish / GameProgrammingS.iso / developer_install / CEGUISDK-0.4.1-VC6-STLport.exe / {app} / include / CEGUIFont.h < prev    next >
C/C++ Source or Header  |  2005-07-22  |  40KB  |  1,092 lines

  1. /************************************************************************
  2.     filename:     CEGUIFont.h
  3.     created:    21/2/2004
  4.     author:        Paul D Turner
  5.     
  6.     purpose:    Defines interface for the Font class
  7. *************************************************************************/
  8. /*************************************************************************
  9.     Crazy Eddie's GUI System (http://www.cegui.org.uk)
  10.     Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk)
  11.  
  12.     This library is free software; you can redistribute it and/or
  13.     modify it under the terms of the GNU Lesser General Public
  14.     License as published by the Free Software Foundation; either
  15.     version 2.1 of the License, or (at your option) any later version.
  16.  
  17.     This library is distributed in the hope that it will be useful,
  18.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  19.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20.     Lesser General Public License for more details.
  21.  
  22.     You should have received a copy of the GNU Lesser General Public
  23.     License along with this library; if not, write to the Free Software
  24.     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  25. *************************************************************************/
  26. #ifndef _CEGUIFont_h_
  27. #define _CEGUIFont_h_
  28.  
  29. #include "CEGUIBase.h"
  30. #include "CEGUIString.h"
  31. #include "CEGUIRect.h"
  32. #include "CEGUIVector.h"
  33. #include "CEGUIColourRect.h"
  34.  
  35. #include <map>
  36.  
  37.  
  38. #if defined(_MSC_VER)
  39. #    pragma warning(push)
  40. #    pragma warning(disable : 4251)
  41. #endif
  42.  
  43.  
  44. // Start of CEGUI namespace section
  45. namespace CEGUI
  46. {
  47. /*!
  48. \brief
  49.     Enumerated type that contains the valid flags that can be passed to createFont when creating a new font.
  50. */
  51. enum FontFlag
  52. {
  53.     Default,            //!< Default / None.
  54.     NoAntiAlias         //!< Fonts generated from TrueType files should not be anti-aliased.
  55. };
  56.  
  57.  
  58. /*!
  59. \brief
  60.     Enumerated type that contains valid formatting types that can be specified when rendering text into a Rect area (the formatting Rect).
  61. */
  62. enum TextFormatting
  63. {
  64.     LeftAligned,            //!< All text is printed on a single line.  The left-most character is aligned with the left edge of the formatting Rect.
  65.     RightAligned,            //!< All text is printed on a single line.  The right-most character is aligned with the right edge of the formatting Rect.
  66.     Centred,                //!< All text is printed on a single line.  The text is centred horizontally in the formatting Rect.
  67.     Justified,                //!< All text is printed on a single line.  The left-most and right-most characters are aligned with the edges of the formatting Rect.
  68.     WordWrapLeftAligned,    //!< Text is broken into multiple lines no wider than the formatting Rect.  The left-most character of each line is aligned with the left edge of the formatting Rect.
  69.     WordWrapRightAligned,    //!< Text is broken into multiple lines no wider than the formatting Rect.  The right-most character of each line is aligned with the right edge of the formatting Rect.
  70.     WordWrapCentred,         //!< Text is broken into multiple lines no wider than the formatting Rect.  Each line is centred horizontally in the formatting Rect.
  71.     WordWrapJustified         //!< Text is broken into multiple lines no wider than the formatting Rect.  The left-most and right-most characters of each line are aligned with the edges of the formatting Rect.
  72. };
  73.  
  74. /*!
  75. \brief
  76.     Class that encapsulates text rendering functionality for a typeface
  77.  
  78.     A Font object is created for each unique typeface required.  The Font class provides
  79.     methods for loading typefaces from various sources, and then for outputting text via
  80.     the Renderer object.
  81. */
  82. class CEGUIEXPORT Font
  83. {
  84.     friend class Font_xmlHandler;
  85. public:
  86.     /*************************************************************************
  87.         Constants
  88.     *************************************************************************/
  89.     static const argb_t        DefaultColour;            //!< Colour value used whenever a colour is not specified.
  90.  
  91.  
  92.     /*************************************************************************
  93.         Text drawing methods
  94.     *************************************************************************/
  95.     /*!
  96.     \brief
  97.         Draw text into a specified area of the display.
  98.  
  99.     \param text
  100.         String object containing the text to be drawn.
  101.  
  102.     \param draw_area
  103.         Rect object describing the area of the display where the text is to be rendered.  The text is not clipped to this Rect, but is formatted
  104.         using this Rect depending upon the option specified in \a fmt.
  105.  
  106.     \param z
  107.         flat value specifying the z co-ordinate for the drawn text.
  108.  
  109.     \param clip_rect
  110.         Rect object describing the clipping area for the drawing.  No drawing will occur outside this Rect.
  111.  
  112.     \param fmt
  113.         One of the TextFormatting values specifying the text formatting required.
  114.  
  115.     \param colours
  116.         ColourRect object describing the colours to be applied when drawing the text.  NB: The colours specified in here are applied to each glyph,
  117.         rather than the text as a whole.
  118.  
  119.     \param x_scale
  120.         Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
  121.  
  122.     \param y_scale
  123.         Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.
  124.  
  125.     \return
  126.         The number of lines output.  NB: This does not consider clipping, so if all text was clipped, this would still return >=1.
  127.     */
  128.     size_t    drawText(const String& text, const Rect& draw_area, float z, const Rect& clip_rect, TextFormatting fmt, const ColourRect& colours, float x_scale = 1.0f, float y_scale = 1.0f) const;
  129.  
  130.  
  131.     /*!
  132.     \brief
  133.         Draw text into a specified area of the display using default colours.
  134.  
  135.     \param text
  136.         String object containing the text to be drawn.
  137.  
  138.     \param draw_area
  139.         Rect object describing the area of the display where the text is to be rendered.  The text is not clipped to this Rect, but is formatted
  140.         using this Rect depending upon the option specified in \a fmt.
  141.  
  142.     \param z
  143.         flat value specifying the z co-ordinate for the drawn text.
  144.  
  145.     \param clip_rect
  146.         Rect object describing the clipping area for the drawing.  No drawing will occur outside this Rect.
  147.  
  148.     \param fmt
  149.         One of the TextFormatting values specifying the text formatting required.
  150.  
  151.     \param x_scale
  152.         Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
  153.  
  154.     \param y_scale
  155.         Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.
  156.  
  157.     \return
  158.         The number of lines output.  NB: This does not consider clipping, so if all text was clipped, this would still return >=1.
  159.     */
  160.     size_t    drawText(const String& text, const Rect& draw_area, float z, const Rect& clip_rect, TextFormatting fmt, float x_scale = 1.0f, float y_scale = 1.0f) const
  161.     { return drawText(text, draw_area, z, clip_rect, fmt, ColourRect(DefaultColour, DefaultColour, DefaultColour, DefaultColour), x_scale, y_scale); }
  162.  
  163.  
  164.     /*!
  165.     \brief
  166.         Draw text into a specified area of the display with default colours and default formatting (LeftAligned).
  167.  
  168.     \param text
  169.         String object containing the text to be drawn.
  170.  
  171.     \param draw_area
  172.         Rect object describing the area of the display where the text is to be rendered.  The text is not clipped to this Rect, but is formatted
  173.         using this Rect depending upon the option specified in \a fmt.
  174.  
  175.     \param z
  176.         flat value specifying the z co-ordinate for the drawn text.
  177.  
  178.     \param clip_rect
  179.         Rect object describing the clipping area for the drawing.  No drawing will occur outside this Rect.
  180.  
  181.     \param x_scale
  182.         Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
  183.  
  184.     \param y_scale
  185.         Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.
  186.  
  187.     \return
  188.         Nothing.
  189.     */
  190.     void    drawText(const String& text, const Rect& draw_area, float z, const Rect& clip_rect, float x_scale = 1.0f, float y_scale = 1.0f) const
  191.     { drawText(text, draw_area, z, clip_rect, LeftAligned, ColourRect(DefaultColour, DefaultColour, DefaultColour, DefaultColour), x_scale, y_scale); }
  192.  
  193.  
  194.     /*!
  195.     \brief
  196.         Draw text into a specified area of the display.
  197.  
  198.     \param text
  199.         String object containing the text to be drawn.
  200.  
  201.     \param draw_area
  202.         Rect object describing the area of the display where the text is to be rendered.  The text is formatted using this Rect depending
  203.         upon the option specified in \a fmt.  Additionally, the drawn text is clipped to be within this Rect (applies to non-word wrapped formatting
  204.         where the text may otherwise have fallen outside this Rect).
  205.  
  206.     \param z
  207.         flat value specifying the z co-ordinate for the drawn text.
  208.  
  209.     \param fmt
  210.         One of the TextFormatting values specifying the text formatting required.
  211.  
  212.     \param colours
  213.         ColourRect object describing the colours to be applied when drawing the text.  NB: The colours specified in here are applied to each glyph,
  214.         rather than the text as a whole.
  215.  
  216.     \param x_scale
  217.         Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
  218.  
  219.     \param y_scale
  220.         Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.
  221.  
  222.     \return
  223.         The number of lines output.  NB: This does not consider clipping, so if all text was clipped, this would still return >=1.
  224.     */
  225.     size_t    drawText(const String& text, const Rect& draw_area, float z, TextFormatting fmt, const ColourRect& colours, float x_scale = 1.0f, float y_scale = 1.0f) const
  226.     { return drawText(text, draw_area, z, draw_area, fmt, colours, x_scale, y_scale); }
  227.  
  228.  
  229.     /*!
  230.     \brief
  231.         Draw text into a specified area of the display with default colours.
  232.  
  233.     \param text
  234.         String object containing the text to be drawn.
  235.  
  236.     \param draw_area
  237.         Rect object describing the area of the display where the text is to be rendered.  The text is formatted using this Rect depending
  238.         upon the option specified in \a fmt.  Additionally, the drawn text is clipped to be within this Rect (applies to non-word wrapped formatting
  239.         where the text may otherwise have fallen outside this Rect).
  240.  
  241.     \param z
  242.         flat value specifying the z co-ordinate for the drawn text.
  243.  
  244.     \param fmt
  245.         One of the TextFormatting values specifying the text formatting required.
  246.  
  247.     \param x_scale
  248.         Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
  249.  
  250.     \param y_scale
  251.         Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.
  252.  
  253.     \return
  254.         The number of lines output.  NB: This does not consider clipping, so if all text was clipped, this would still return >=1.
  255.     */
  256.     size_t    drawText(const String& text, const Rect& draw_area, float z, TextFormatting fmt, float x_scale = 1.0f, float y_scale = 1.0f) const
  257.     { return drawText(text, draw_area, z, draw_area, fmt, ColourRect(DefaultColour, DefaultColour, DefaultColour, DefaultColour), x_scale, y_scale); }
  258.  
  259.  
  260.     /*!
  261.     \brief
  262.         Draw text into a specified area of the display with default colours and default formatting (LeftAligned).
  263.  
  264.     \param text
  265.         String object containing the text to be drawn.
  266.  
  267.     \param draw_area
  268.         Rect object describing the area of the display where the text is to be rendered.  The text is formatted using this Rect depending
  269.         upon the option specified in \a fmt.  Additionally, the drawn text is clipped to be within this Rect (applies to non-word wrapped formatting
  270.         where the text may otherwise have fallen outside this Rect).
  271.  
  272.     \param z
  273.         flat value specifying the z co-ordinate for the drawn text.
  274.  
  275.     \param x_scale
  276.         Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
  277.  
  278.     \param y_scale
  279.         Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.
  280.  
  281.     \return
  282.         Nothing.
  283.     */
  284.     void    drawText(const String& text, const Rect& draw_area, float z, float x_scale = 1.0f, float y_scale = 1.0f) const
  285.     { drawText(text, draw_area, z, draw_area, LeftAligned, ColourRect(DefaultColour, DefaultColour, DefaultColour, DefaultColour), x_scale, y_scale); }
  286.  
  287.  
  288.     /*!
  289.     \brief
  290.         Draw text at the specified location.
  291.  
  292.     \param text
  293.         String object containing the text to be drawn.
  294.  
  295.     \param position
  296.         Vector3 object describing the location for the text.  NB: The position specified here corresponds to the text baseline and not the
  297.         top of any glyph.  The baseline spacing required can be retrieved by calling getBaseline().
  298.         
  299.     \param clip_rect
  300.         Rect object describing the clipping area for the drawing.  No drawing will occur outside this Rect.
  301.  
  302.     \param colours
  303.         ColourRect object describing the colours to be applied when drawing the text.  NB: The colours specified in here are applied to each glyph,
  304.         rather than the text as a whole.
  305.  
  306.     \param x_scale
  307.         Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
  308.  
  309.     \param y_scale
  310.         Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.
  311.  
  312.     \return
  313.         Nothing.
  314.     */
  315.     void    drawText(const String& text, const Vector3& position, const Rect& clip_rect, const ColourRect& colours, float x_scale = 1.0f, float y_scale = 1.0f) const
  316.     { drawText(text, Rect(position.d_x, position.d_y, position.d_x, position.d_y), position.d_z, clip_rect, LeftAligned, colours, x_scale, y_scale); }
  317.  
  318.  
  319.     /*!
  320.     \brief
  321.         Draw text at the specified location with default colours.
  322.  
  323.     \param text
  324.         String object containing the text to be drawn.
  325.  
  326.     \param position
  327.         Vector3 object describing the location for the text.  NB: The position specified here corresponds to the text baseline and not the
  328.         top of any glyph.  The baseline spacing required can be retrieved by calling getBaseline().
  329.         
  330.     \param clip_rect
  331.         Rect object describing the clipping area for the drawing.  No drawing will occur outside this Rect.
  332.  
  333.     \param x_scale
  334.         Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
  335.  
  336.     \param y_scale
  337.         Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.
  338.  
  339.     \return
  340.         Nothing.
  341.     */
  342.     void    drawText(const String& text, const Vector3& position, const Rect& clip_rect, float x_scale = 1.0f, float y_scale = 1.0f) const
  343.     { drawText(text, Rect(position.d_x, position.d_y, position.d_x, position.d_y), position.d_z, clip_rect, LeftAligned, ColourRect(DefaultColour, DefaultColour, DefaultColour, DefaultColour), x_scale, y_scale); }
  344.  
  345.  
  346.     /*************************************************************************
  347.         Methods to define available glyphs (truetype fonts only)
  348.     *************************************************************************/
  349.     /*!
  350.     \brief
  351.         Define the set of code points to be renderable by the font.
  352.  
  353.     \note
  354.         This function can take some time to execute depending upon the size of the code point set, and the size of the
  355.         font being operated upon.
  356.  
  357.     \param glyph_set
  358.         String object describing all the code points that will be renderable by this font
  359.  
  360.     \return
  361.         Nothing
  362.  
  363.     \exception    InvalidRequestException        thrown if the font is based on a bitmap rather than a true-type font.
  364.     \exception    RendererException            thrown if the Renderer can't support a texture large enough to hold the glyph imagery.
  365.     \exception    MemoryException                thrown if allocation of imagery construction buffer fails.
  366.     */
  367.     void    defineFontGlyphs(const String& glyph_set);
  368.  
  369.  
  370.     /*!
  371.     \brief
  372.         Define the range of code points to be renderable by the font.
  373.  
  374.     \note
  375.         This function can take some time to execute depending upon the size of the code point set, and the size of the
  376.         font being operated upon.
  377.  
  378.     \note
  379.         The code point arguments must satisfy the following:  \a first_code_point <= \a last_code_point, otherwise results are undefined
  380.  
  381.     \param first_code_point
  382.         utf32 value describing the first code point that will be renderable by this font.
  383.  
  384.     \param last_code_point
  385.         utf32 value describing the last code point that will be renderable by this font.
  386.  
  387.     \return
  388.         Nothing
  389.  
  390.     \exception    InvalidRequestException        thrown if the font is based on a bitmap rather than a true-type font.
  391.     \exception    RendererException            thrown if the Renderer can't support a texture large enough to hold the glyph imagery.
  392.     \exception    MemoryException                thrown if allocation of imagery construction buffer fails.
  393.     */
  394.     void    defineFontGlyphs(utf32 first_code_point, utf32 last_code_point);
  395.  
  396.  
  397.     /*!
  398.     \brief
  399.         Set the native resolution for this Font
  400.  
  401.     \param size
  402.         Size object describing the new native screen resolution for this Font.
  403.  
  404.     \return
  405.         Nothing
  406.     */
  407.     void    setNativeResolution(const Size& size);
  408.  
  409.  
  410.     /*!
  411.     \brief
  412.         Notify the Font of the current (usually new) display resolution.
  413.  
  414.     \param size
  415.         Size object describing the display resolution
  416.  
  417.     \return
  418.         Nothing
  419.     */
  420.     void    notifyScreenResolution(const Size& size);
  421.  
  422.  
  423.     /*!
  424.     \brief
  425.         Enable or disable auto-scaling for this Font.
  426.  
  427.     \param setting
  428.         true to enable auto-scaling, false to disable auto-scaling.
  429.  
  430.     \return
  431.         Nothing.
  432.     */
  433.     void    setAutoScalingEnabled(bool setting);
  434.  
  435.  
  436.     /*!
  437.     \brief
  438.         Set whether the font is anti-aliased or not.  Only relevant for dynamic fonts, this setting is
  439.         ignored for bitmapped fonts.
  440.  
  441.     \param setting
  442.         - true if the font should be anti-aliased.
  443.         - false if the font should not be anti-aliased.
  444.  
  445.     \return
  446.         Nothing.
  447.     */
  448.     void    setAntiAliased(bool setting);
  449.  
  450.  
  451.     /*************************************************************************
  452.         Informational methods
  453.     *************************************************************************/
  454.     /*!
  455.     \brief
  456.         Return the pixel width of the specified text if rendered with this Font.
  457.  
  458.     \param text
  459.         String object containing the text to return the rendered pixel width for.
  460.  
  461.     \param x_scale
  462.         Scaling factor to be applied to each glyph's x axis when measuring the extent, where 1.0f is considered to be 'normal'.
  463.  
  464.     \return
  465.         Number of pixels that \a text will occupy when rendered with this Font.
  466.     */
  467.     float    getTextExtent(const String& text, float x_scale = 1.0f) const;
  468.  
  469.  
  470.     /*!
  471.     \brief
  472.         Return the pixel line spacing value for.
  473.  
  474.     \param y_scale
  475.         Scaling factor to be applied to the line spacing, where 1.0f is considered to be 'normal'.
  476.  
  477.     \return
  478.         Number of pixels between vertical base lines, i.e. The minimum pixel space between two lines of text.
  479.     */
  480.     float    getLineSpacing(float y_scale = 1.0f) const        {return d_lineSpacing * y_scale;}
  481.  
  482.  
  483.     /*!
  484.     \brief
  485.         return the exact pixel height of the font.
  486.  
  487.     \param y_scale
  488.         Scaling factor to be applied to the height, where 1.0f is considered to be 'normal'.
  489.  
  490.     \return
  491.         float value describing the pixel height of the font without any additional padding.
  492.     */
  493.     float    getFontHeight(float y_scale = 1.0f) const    {return d_lineHeight * y_scale;}
  494.  
  495.  
  496.     /*!
  497.     \brief
  498.         Return the number of pixels from the top of the highest glyph to the baseline
  499.  
  500.     \param y_scale
  501.         Scaling factor to be applied to the baseline distance, where 1.0f is considered to be 'normal'.
  502.  
  503.     \return
  504.         pixel spacing from top of front glyphs to baseline
  505.     */
  506.     float    getBaseline(float y_scale = 1.0f) const            {return d_max_bearingY * y_scale;}
  507.  
  508.  
  509.     /*!
  510.     \brief
  511.         Return the index of the closest text character in String \a text that corresponds to pixel location \a pixel if the text were rendered.
  512.  
  513.     \param text
  514.         String object containing the text.
  515.  
  516.     \param pixel
  517.         Specifies the (horizontal) pixel offset to return the character index for.
  518.  
  519.     \param x_scale
  520.         Scaling factor to be applied to each glyph's x axis when measuring the text extent, where 1.0f is considered to be 'normal'.
  521.  
  522.     \return
  523.         Returns a character index into String \a text for the character that would be rendered closest to horizontal pixel offset \a pixel if the
  524.         text were to be rendered via this Font.  Range of the return is from 0 to text.length(), so may actually return an index past the end of
  525.         the string, which indicates \a pixel was beyond the last character.
  526.     */
  527.     size_t    getCharAtPixel(const String& text, float pixel, float x_scale = 1.0f) const        {return getCharAtPixel(text, 0, pixel, x_scale);}
  528.  
  529.  
  530.     /*!
  531.     \brief
  532.         Return the index of the closest text character in String \a text, starting at character index \a start_char, that corresponds
  533.         to pixel location \a pixel if the text were to be rendered.
  534.  
  535.     \param text
  536.         String object containing the text.
  537.  
  538.     \param start_char
  539.         index of the first character to consider.  This is the lowest value that will be returned from the call.
  540.  
  541.     \param pixel
  542.         Specifies the (horizontal) pixel offset to return the character index for.
  543.  
  544.     \param x_scale
  545.         Scaling factor to be applied to each glyph's x axis when measuring the text extent, where 1.0f is considered to be 'normal'.
  546.  
  547.     \return
  548.         Returns a character index into String \a text for the character that would be rendered closest to horizontal pixel offset \a pixel if the
  549.         text were to be rendered via this Font.  Range of the return is from 0 to text.length(), so may actually return an index past the end of
  550.         the string, which indicates \a pixel was beyond the last character.
  551.     */
  552.     size_t    getCharAtPixel(const String& text, size_t start_char, float pixel, float x_scale = 1.0f) const;
  553.  
  554.  
  555.     /*!
  556.     \brief
  557.         Return the name of this font.
  558.  
  559.     \return
  560.         String object holding the name of this font.
  561.     */
  562.     const String&    getName(void) const        {return    d_name;}
  563.  
  564.  
  565.     /*!
  566.     \brief
  567.         Return the native display size for this Font.  This is only relevant if the Font is being auto-scaled.
  568.  
  569.     \return
  570.         Size object describing the native display size for this Font.
  571.     */
  572.     Size    getNativeResolution(void) const    {return Size(d_nativeHorzRes, d_nativeVertRes);}
  573.  
  574.  
  575.     /*!
  576.     \brief
  577.         Return whether this Font is auto-scaled.
  578.  
  579.     \return
  580.         true if the Font is auto-scaled, false if not.
  581.     */
  582.     bool    isAutoScaled(void) const        {return d_autoScale;}
  583.  
  584.  
  585.     /*!
  586.     \brief
  587.         Return whether this Font can currently draw the specified code-point
  588.  
  589.     \param cp
  590.         utf32 code point that is the subject of the query.
  591.  
  592.     \return
  593.         true if the font contains a mapping for code point \a cp, false if it does not contain a mapping for \a cp.
  594.     */
  595.     bool    isCodepointAvailable(utf32 cp) const        {return (d_cp_map.find(cp) != d_cp_map.end());}
  596.  
  597.  
  598.     /*!
  599.     \brief
  600.         Return the number of lines the given text would be formatted to.
  601.  
  602.         Since text formatting can result in multiple lines of text being output, it can be useful to know
  603.         how many lines would be output without actually rendering the text.
  604.  
  605.     \param text
  606.         String object containing the text to be measured.
  607.  
  608.     \param format_area
  609.         Rect object describing the area to be used when formatting the text depending upon the option specified in \a fmt.
  610.  
  611.     \param fmt
  612.         One of the TextFormatting values specifying the text formatting required.
  613.  
  614.     \param x_scale
  615.         Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
  616.  
  617.     \return
  618.         The number of lines produced from the specified formatting
  619.     */
  620.     size_t    getFormattedLineCount(const String& text, const Rect& format_area, TextFormatting fmt, float x_scale = 1.0f) const;
  621.  
  622.  
  623.     /*!
  624.     \brief
  625.         Return the horizontal pixel extent given text would be formatted to.
  626.  
  627.         The value return by this method is basically the extent of the widest line within the formatted text.
  628.  
  629.     \param text
  630.         String object containing the text to be measured.
  631.  
  632.     \param format_area
  633.         Rect object describing the area to be used when formatting the text depending upon the option specified in \a fmt.
  634.  
  635.     \param fmt
  636.         One of the TextFormatting values specifying the text formatting required.
  637.  
  638.     \param x_scale
  639.         Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
  640.  
  641.     \return
  642.         The widest pixel extent of the lines produced from the specified formatting.
  643.     */
  644.     float    getFormattedTextExtent(const String& text, const Rect& format_area, TextFormatting fmt, float x_scale = 1.0f) const;
  645.  
  646.  
  647.     /*!
  648.     \brief
  649.         Return whether this font is anti-aliased or not.  This is only relevant for dynamic fonts created from a TrueType font file.
  650.  
  651.     \return
  652.         - true if the font is anti-aliased.
  653.         - false if the font is not anti-aliased.
  654.     */
  655.     bool    isAntiAliased(void) const;
  656.  
  657.  
  658.     /*!
  659.     \brief
  660.         Return a String object that contains the code-points that the font is currently configured to render.
  661.  
  662.     \return
  663.         Reference to a String object.
  664.     */
  665.     const String& getAvailableGlyphs(void) const;
  666.  
  667.  
  668.     /*!
  669.     \brief
  670.         Return the point size of a dynamic (ttf based) font.
  671.  
  672.     \return
  673.         uint value indicating the point size specified when the dynamic font was created.
  674.  
  675.     \exception InvalidRequestException        thrown if the font is a static (bitmap based) font which do not support point sizes.
  676.     */
  677.     uint    getPointSize(void) const;
  678.  
  679.  
  680. private:
  681.     /*************************************************************************
  682.         Implementation Constants
  683.     *************************************************************************/
  684.     static const char    FontSchemaName[];            //!< Filename of the XML schema used for validating Font files.
  685.     static const uint    InterGlyphPadSpace;            //!< Pad space between glyphs.
  686.  
  687.  
  688.     /*************************************************************************
  689.         Friends so that only FontManager can create and destroy font objects
  690.     *************************************************************************/
  691.     friend class FontManager;
  692.  
  693.     /*************************************************************************
  694.         Private forward refs
  695.     *************************************************************************/
  696.     struct FontImplData;
  697.  
  698.  
  699.     /*************************************************************************
  700.         Construction & Destruction
  701.     *************************************************************************/
  702.     /*!
  703.     \brief
  704.         Constructs a new Font object
  705.  
  706.     \param filename
  707.         The filename of the "font definition file" to be used in creating this font.
  708.  
  709.     \param resourceGroup
  710.         Resource group identifier to be passed to the resource provider to load the font
  711.         definition file.
  712.  
  713.     \exception    FileIOException                thrown if there was some problem accessing or parsing the file \a filename
  714.     \exception    InvalidRequestException        thrown if an invalid filename was provided.
  715.     \exception    AlreadyExistsException        thrown if a Font Imageset clashes with one already defined in the system.
  716.     \exception    GenericException            thrown if something goes wrong while accessing a true-type font referenced in file \a filename.
  717.     \exception    RendererException            thrown if the Renderer can't support a texture large enough to hold the requested glyph imagery.
  718.     \exception    MemoryException                thrown if allocation of imagery construction buffer fails.
  719.     */
  720.     Font(const String& filename, const String& resourceGroup, FontImplData* dat);
  721.  
  722.  
  723.     /*!
  724.     \brief
  725.         Constructs a new Font object, with 7-bit ASCII glyphs
  726.  
  727.     \param name
  728.         The unique name that will be used to identify this Font.
  729.  
  730.     \param fontname
  731.         filename of the true-type font to be loaded.
  732.  
  733.     \param resourceGroup
  734.         Resource group identifier to pass to the resource provider when loading the true-type
  735.         font file.
  736.  
  737.     \param size
  738.         Point size of the new font.
  739.  
  740.     \param flags
  741.         Combination of the FontFlag enumerated values specifying required options for creating this Font.
  742.  
  743.     \exception    AlreadyExistsException        thrown if an auto-generated Imageset clashes with one already defined in the system.
  744.     \exception    GenericException            thrown if something goes wrong while accessing the true-type font \a fontname.
  745.     \exception    RendererException            thrown if the Renderer can't support a texture large enough to hold the requested glyph imagery.
  746.     \exception    MemoryException                thrown if allocation of imagery construction buffer fails.
  747.     */
  748.     Font(const String& name, const String& fontname, const String& resourceGroup, uint size, uint flags, FontImplData* dat);
  749.  
  750.  
  751.     /*!
  752.     \brief
  753.         Constructs a new Font object, with the specified set of glyphs
  754.  
  755.     \param name
  756.         The unique name that will be used to identify this Font.
  757.  
  758.     \param fontname
  759.         filename of the true-type font to be loaded.
  760.  
  761.     \param resourceGroup
  762.         Resource group identifier to pass to the resource provider when loading the true-type
  763.         font file.
  764.  
  765.     \param size
  766.         Point size of the new font.
  767.  
  768.     \param flags
  769.         Combination of the FontFlag enumerated values specifying required options for creating this Font.
  770.  
  771.     \param glyph_set
  772.         String containing the set of glyphs to have available in this font.
  773.  
  774.     \exception    AlreadyExistsException        thrown if an auto-generated Imageset clashes with one already defined in the system.
  775.     \exception    GenericException            thrown if something goes wrong while accessing the true-type font \a fontname.
  776.     \exception    RendererException            thrown if the Renderer can't support a texture large enough to hold the requested glyph imagery.
  777.     \exception    MemoryException                thrown if allocation of imagery construction buffer fails.
  778.     */
  779.     Font(const String& name, const String& fontname, const String& resourceGroup, uint size, uint flags, const String& glyph_set, FontImplData* dat);
  780.  
  781.  
  782.     /*!
  783.     \brief
  784.         Constructs a new Font object, with a specified range of glyphs
  785.  
  786.     \param name
  787.         The unique name that will be used to identify this Font.
  788.  
  789.     \param fontname
  790.         filename of the true-type font to be loaded.
  791.  
  792.     \param resourceGroup
  793.         Resource group identifier to pass to the resource provider when loading the true-type
  794.         font file.
  795.  
  796.     \param size
  797.         Point size of the new font.
  798.  
  799.     \param flags
  800.         Combination of the FontFlag enumerated values specifying required options for creating this Font.
  801.  
  802.     \param first_code_point
  803.         Specifies the utf32 code point of the first glyph to be available on this font
  804.  
  805.     \param last_code_point
  806.         Specifies the utf32 code point of the last glyph to be available on this font
  807.  
  808.     \exception    AlreadyExistsException        thrown if an auto-generated Imageset clashes with one already defined in the system.
  809.     \exception    GenericException            thrown if something goes wrong while accessing the true-type font \a fontname.
  810.     \exception    RendererException            thrown if the Renderer can't support a texture large enough to hold the requested glyph imagery.
  811.     \exception    MemoryException                thrown if allocation of imagery construction buffer fails.
  812.     */
  813.     Font(const String& name, const String& fontname, const String& resourceGroup, uint size, uint flags, utf32 first_code_point, utf32 last_code_point, FontImplData* dat);
  814.  
  815.  
  816. public:        // For luabind support
  817.     /*!
  818.     \brief
  819.         Destroys a Font object
  820.     */
  821.     ~Font(void);
  822.  
  823.  
  824. private:
  825.     /*************************************************************************
  826.         Implementation Methods
  827.     *************************************************************************/
  828.     /*!
  829.     \brief
  830.         Load and complete construction of 'this' via an XML file
  831.  
  832.     \param filename
  833.         String object holding the name of the XML file that holds details about the font to create.
  834.  
  835.     \param resourceGroup
  836.         Resource group identifier to be passed to the resource provider when loading the font
  837.         definition file.
  838.  
  839.     \return
  840.         Nothing.
  841.     */
  842.     void    load(const String& filename, const String& resourceGroup);
  843.  
  844.  
  845.     /*!
  846.     \brief
  847.         Unloads data associated with the font (font is then useless.  this is intended for cleanup).
  848.  
  849.     \return
  850.         Nothing.
  851.     */
  852.     void    unload(void);
  853.  
  854.  
  855.     /*!
  856.     \brief
  857.         Return the required texture size required to store imagery for the
  858.         glyphs specified in \a glyph_set
  859.  
  860.     \param glyph_set
  861.         String object describing the set of code points who's glyph imagery is to be measured.
  862.  
  863.     \return
  864.         Required pixel size for a square texture large enough to hold glyph imagery for the set of code points in \a glyph_set
  865.     */
  866.     uint    getRequiredTextureSize(const String& glyph_set);
  867.  
  868.  
  869.     /*!
  870.     \brief
  871.         Return the required texture size required to store imagery for the
  872.         glyphs specified in by the inclusive range [first_code_point, last_code_point]
  873.  
  874.     \param first_code_point
  875.         utf32 code point of the first character in the range to be measured
  876.  
  877.     \param last_code_point
  878.         utf32 code point of the last character in the range to be measured
  879.  
  880.     \return
  881.         Required pixel size for a square texture large enough to hold glyph imagery for the specified range of code points.
  882.     */
  883.     uint    getRequiredTextureSize(utf32 first_code_point, utf32 last_code_point);
  884.  
  885.  
  886.     /*!
  887.     \brief
  888.         Paint the set of glyphs required for all code points in \a glyph_set into the buffer \a buffer,
  889.         which has a size of \a size pixels (not bytes) square.  This also defines an Image for each
  890.         glyph in the Imageset for this font, and creates an entry in the code point to Image map.
  891.  
  892.     \param glyph_set
  893.         String object containing the set of code points whos glyphs are to be loaded into the buffer.
  894.  
  895.     \param size
  896.         Width of \a buffer in pixels (not bytes).
  897.  
  898.     \param buffer
  899.         Pointer to a memory buffer large enough to receive the glyph image data.
  900.  
  901.     \return
  902.         Nothing.
  903.     */
  904.     void    createFontGlyphSet(const String& glyph_set, uint size, argb_t* buffer);
  905.  
  906.  
  907.     /*!
  908.     \brief
  909.         Paint the set of glyphs required for all code points in the range [\a first_code_point, \a last_code_point]
  910.         into the buffer \a buffer, which has a size of \a size pixels (not bytes) square.  This also defines an
  911.         Image for each glyph in the Imageset for this font, and creates an entry in the code point to Image map.
  912.  
  913.     \param first_code_point
  914.         utf32 code point that is the first code point in a range whos glyph are to be loaded into the buffer.
  915.  
  916.     \param last_code_point
  917.         utf32 code point that is the last code point in a range whos glyph are to be loaded into the buffer.
  918.  
  919.     \param size
  920.         Width of \a buffer in pixels (not bytes).
  921.  
  922.     \param buffer
  923.         Pointer to a memory buffer large enough to receive the glyph image data.
  924.  
  925.     \return
  926.         Nothing.
  927.     */
  928.     void    createFontGlyphSet(utf32 first_code_point, utf32 last_code_point, uint size, argb_t* buffer);
  929.  
  930.  
  931.     /*!
  932.     \brief
  933.         Copy the current glyph data into \a buffer, which has a width of \a buf_width pixels (not bytes).
  934.  
  935.     \param buffer
  936.         Memory buffer large enough to receive the imagery for the currently loaded glyph.
  937.  
  938.     \param buf_width
  939.         Width of \a buffer in pixels (where each pixel is a argb_t).
  940.  
  941.     \return
  942.         Nothing.
  943.     */
  944.     void    drawGlyphToBuffer(argb_t* buffer, uint buf_width);
  945.  
  946.  
  947.     /*!
  948.     \brief
  949.         draws wrapped text.  returns number of lines output.
  950.     */
  951.     size_t    drawWrappedText(const String& text, const Rect& draw_area, float z, const Rect& clip_rect, TextFormatting fmt, const ColourRect& colours, float x_scale = 1.0f, float y_scale = 1.0f) const;
  952.  
  953.  
  954.     /*!
  955.     \brief
  956.         helper function for renderWrappedText to get next word of a string
  957.     */
  958.     size_t    getNextWord(const String& in_string, size_t start_idx, String& out_string) const;
  959.  
  960.  
  961.     /*!
  962.     \brief
  963.         Draw a line of text.  No formatting is applied.
  964.     */
  965.     void    drawTextLine(const String& text, const Vector3& position, const Rect& clip_rect, const ColourRect& colours, float x_scale = 1.0f, float y_scale = 1.0f) const;
  966.  
  967.  
  968.     /*!
  969.     \brief
  970.         Draw a justified line of text.
  971.     */
  972.     void    drawTextLineJustified(const String& text, const Rect& draw_area, const Vector3& position, const Rect& clip_rect, const ColourRect& colours, float x_scale = 1.0f, float y_scale = 1.0f) const;
  973.  
  974.  
  975.     /*!
  976.     \brief
  977.         Set the size of the free-type font (via d_face which should already be setup) and render the glyphs in d_glyphset.
  978.     */
  979.     void    createFontFromFT_Face(uint size, uint horzDpi, uint vertDpi);
  980.  
  981.  
  982.     /*!
  983.     \brief
  984.         Update the font as required according to the current scaling
  985.     */
  986.     void    updateFontScaling(void);
  987.  
  988.  
  989.     /*!
  990.     \brief
  991.         Calculate the vertical spacing fields for a static / bitmap font
  992.     */
  993.     void    calculateStaticVertSpacing(void);
  994.  
  995.     /*!
  996.     \brief
  997.         Function to do real work of constructor.  Used to save duplication in the various constructor overloads.
  998.     */
  999.     void    constructor_impl(const String& name, const String& fontname, const String& resourceGroup, uint size, uint flags, const String& glyph_set);
  1000.  
  1001.  
  1002.     /*!
  1003.     \brief
  1004.         Defines the set of code points on the font. (implementation).
  1005.  
  1006.     \note
  1007.         This function can take some time to execute depending upon the size of the code point set, and the size of the
  1008.         font being operated upon.
  1009.  
  1010.     \return
  1011.         Nothing
  1012.  
  1013.     \exception    InvalidRequestException        thrown if the font is based on a bitmap rather than a true-type font.
  1014.     \exception    RendererException            thrown if the Renderer can't support a texture large enough to hold the glyph imagery.
  1015.     \exception    MemoryException                thrown if allocation of imagery construction buffer fails.
  1016.     */
  1017.     void    defineFontGlyphs_impl(void);
  1018.  
  1019.  
  1020.     /*!
  1021.     \brief
  1022.         returns extent of widest line of wrapped text.
  1023.     */
  1024.     float    getWrappedTextExtent(const String& text, float wrapWidth, float x_scale = 1.0f) const;
  1025.  
  1026.  
  1027.     /*!
  1028.     \brief
  1029.         Writes an xml representation of this Font to \a out_stream.
  1030.  
  1031.     \param out_stream
  1032.         Stream where xml data should be output.
  1033.  
  1034.     \return
  1035.         Nothing.
  1036.     */
  1037.     void writeXMLToStream(OutStream& out_stream) const;
  1038.  
  1039.  
  1040.     /*************************************************************************
  1041.         Implementation structs
  1042.     *************************************************************************/
  1043.     /*!
  1044.     \brief
  1045.         struct to hold extra details about a glyph (required for proper rendering)
  1046.     */
  1047.     struct glyphDat
  1048.     {
  1049.         const Image*    d_image;                //!< The image which will be rendered.
  1050.         int            d_horz_advance;            //!< Amount to advance the pen after rendering this glyph
  1051.         int            d_horz_advance_unscaled;    //!< original unscaled advance value (only used with static / bitmap fonts).
  1052.     };
  1053.  
  1054.     /*************************************************************************
  1055.         Implementation Data
  1056.     *************************************************************************/
  1057.     typedef        std::map<utf32, glyphDat>        CodepointMap;
  1058.     CodepointMap    d_cp_map;    //!< Contains mappings from code points to Image objects
  1059.  
  1060.     String        d_name;            //!< Name of this font.
  1061.     Imageset*    d_glyph_images;    //!< Imageset that holds the glyphs for this font.
  1062.     String     d_sourceFilename;   //!< Holds the name of the file used to create this font (either font file or imagset)
  1063.  
  1064.     bool    d_freetype;            //!< true when the font is a FreeType based font
  1065.     float    d_lineHeight;        //!< Exact pixel height of font.
  1066.     float    d_lineSpacing;        //!< Spacing between multiple lines.
  1067.     float    d_max_bearingY;        //!< Maximum bearingY value (gives required spacing down to baseline).
  1068.     uint    d_maxGlyphHeight;    //!< Height of the largest glyph (calculated in getRequiredTextureSize)
  1069.  
  1070.     FontImplData*    d_impldat;    //!< Implementation data
  1071.     uint        d_ptSize;        //!< Point size of font.
  1072.     String        d_glyphset;        //!< set of glyphs for the dynamic font.
  1073.  
  1074.     // auto-scaling fields
  1075.     bool    d_autoScale;            //!< true when auto-scaling is enabled.
  1076.     float    d_horzScaling;            //!< current horizontal scaling factor.
  1077.     float    d_vertScaling;            //!< current vertical scaling factor.
  1078.     float    d_nativeHorzRes;        //!< native horizontal resolution for this Imageset.
  1079.     float    d_nativeVertRes;        //!< native vertical resolution for this Imageset.
  1080.  
  1081.     bool    d_antiAliased;            //!< True if the font should be rendered as anti-alaised by freeType.
  1082. };
  1083.  
  1084. } // End of  CEGUI namespace section
  1085.  
  1086. #if defined(_MSC_VER)
  1087. #    pragma warning(pop)
  1088. #endif
  1089.  
  1090.  
  1091. #endif    // end of guard _CEGUIFont_h_
  1092.